使用 3D 轨迹列表框 (Trajectory List Box 3D) 节点

3D 轨迹列表框 (Trajectory List Box 3D) 节点可用于创建沿轨迹排列的项的可滚动列表。

Kanzi Studio 有几种类型的轨迹供您使用。您需要不同类型的轨迹时，可以在第三方工具中创建样条轨迹并将其导入到Kanzi Studio 工程中。请参阅轨迹。

3D 轨迹列表框 (Trajectory List Box 3D) 节点上的项会按您将它们添加到 3D 轨迹列表框 (Trajectory List Box 3D) 节点中时所用的顺序显示。要选择 3D 轨迹列表框 (Trajectory List Box 3D) 节点中的项，请点击或轻敲该项。

轨迹尺寸确定了点击和拖动手势的交互区域。如果轨迹过小，用户将不能选择 3D 轨迹列表框 (Trajectory List Box 3D) 节点中的项。为避免这种情况，要确保轨迹足够大。请参阅轨迹。

3D 轨迹列表框 (Trajectory List Box 3D) 节点是 轨迹布局 (Trajectory Layout) 节点的交互版本。请参阅使用轨迹布局 (Trajectory Layout) 节点。

关于如何使用 3D 轨迹列表框 (Trajectory List Box 3D) 节点创建交互可滚动项列表，请参阅轨迹列表框示例。

对于 3D 轨迹列表框 (Trajectory List Box 3D) 节点，您可以：

• 设置 3D 轨迹列表框 (Trajectory List Box 3D) 节点的内容和轨迹类型。请参阅创建 3D 轨迹列表框 (Trajectory List Box 3D) 节点。
• 微调3D 轨迹列表框 (Trajectory List Box 3D) 节点的机制。请参阅微调 3D 轨迹列表框 (Trajectory List Box 3D) 节点的机制。
• 嵌套 3D 轨迹列表框 (Trajectory List Box 3D) 节点，以在 3D 轨迹列表框 (Trajectory List Box 3D) 中创建 3D 轨迹列表框 (Trajectory List Box 3D)，其中每个都可以独立滚动。请参阅嵌套3D 轨迹列表框 (Trajectory List Box 3D)节点。
• 将 3D 轨迹列表框 (Trajectory List Box 3D) 项的属性绑定到 3D 轨迹列表框 (Trajectory List Box 3D) 节点外的节点属性。请参阅绑定到 3D 轨迹列表框 (Trajectory List Box 3D) 节点以外的属性。
• 从 3D 轨迹列表框 (Trajectory List Box 3D) 节点内的节点导航至 页面 (Page) 节点。请参阅从 3D 轨迹列表框 (Trajectory List Box 3D) 节点导航到 页面 (Page) 节点。
• 使用 列表框 (List Box) 触发器在用户与 3D 轨迹列表框 (Trajectory List Box 3D) 节点交互时响应。请参阅在用户与 3D 轨迹列表框 (Trajectory List Box 3D) 节点交互时响应。

创建 3D 轨迹列表框 (Trajectory List Box 3D) 节点

要创建 3D 轨迹列表框 (Trajectory List Box 3D) 节点：

1. 在工程 (Project) 中按下 Alt 并右键点击要在其中创建 3D 轨迹列表框 (Trajectory List Box 3D) 节点的那个节点，然后选择 3D 轨迹列表框 (Trajectory List Box 3D)。
   请注意，您只能在 3D 节点内创建 3D 轨迹列表框 (Trajectory List Box 3D) 节点。
   
   建议

   要查看轨迹，在预览 (Preview) 中点击 进入分析 (Analyze) 模式，右键点击 并选择调试对象 (Debug objects)。
   

2. 在工程 (Project) 中，将项添加到3D 轨迹列表框 (Trajectory List Box 3D) 节点。
   使用数据源为 列表框 (List Box) 节点添加项。请参阅使用数据源。
   例如，要创建相册列表，请添加多个代表列表中的相册的节点。请参阅使用列表框项容器 (List Box Item Container) 预设件。
   添加项时，3D 轨迹列表框 (Trajectory List Box 3D) 节点将其沿 3D 轨迹列表框 (Trajectory List Box 3D) 节点使用的轨迹进行排列。
   要在 3D 轨迹列表框 (Trajectory List Box 3D) 节点中浏览项，请在预览 (Preview) 中点击项并将其拖到 3D 轨迹列表框 (Trajectory List Box 3D) 节点中。
   
   
3. （可选） Kanzi Studio 默认创建并使用圆形轨迹。您可以使用角度、弧形、圆形、椭圆、直线、矩形、螺旋、样条或梯形轨迹。请参阅轨迹。

微调 3D 轨迹列表框 (Trajectory List Box 3D) 节点的机制

您可以微调列表框的机制。您可以将列表框设为：

• 将选定的项放到列表框中心。 要将列表框设为在用户点击或轻敲项时将项置于列表框对象的中心，应将选择行为 (Selection Behavior) 属性设为移动到中心 (Bring Center)。光标偏移 (Cursor Offset) 属性可用于设置选择移动列表框中项的方向。 光标偏移 (Cursor Offset) 属性可用于设置选择移动列表框中项的方向。
  
• 到达最后一个项后，从头开始显示项。 要在到达最后一项后从开头开始显示3D 轨迹列表框 (Trajectory List Box 3D) 中的项，启用循环 (Looping) 属性。
  
• 使用 x 或 y 轴滚动列表框中的项。 要设置滚动轴，添加并设置滚动轴 (Scroll Axis) 属性。例如，要设置列表框使用户可沿 y 轴滚动浏览列表框项，将滚动轴 (Scroll Axis) 属性值 X 设为 0，Y 设为 1。
• 根据项在轨迹上的位置来改变其外观。 要设置项在轨迹上不同点的外观，使用项区域开始 (Item Area Begin) 和项区域结束 (Item Area End) 属性。使用项区域开始 (Item Area Begin) 和项区域结束 (Item Area End) 属性设置父级内可见数量 (Visible Amount In Parent) 属性的值，该属性将着色器设为根据该对象在列表框中的位置来更改项的外观。
  例如，如果使用父级内可见数量 (Visible Amount In Parent) 属性逐渐更改项的可见性，则将项区域开始 (Item Area Begin) 属性设为较大的值，将项区域结束 (Item Area End) 属性设为较小的值。这样可以限制该项可见的区域。

嵌套3D 轨迹列表框 (Trajectory List Box 3D)节点

您可以嵌套3D 轨迹列表框 (Trajectory List Box 3D) 节点，以在3D 轨迹列表框 (Trajectory List Box 3D) 节点中创建3D 轨迹列表框 (Trajectory List Box 3D) 节点，其中每个都可以独立滚动。例如，您可以创建用于在包含相册集的圆形轨迹 3D 轨迹布局 (Trajectory Layout 3D) 节点上滚动的 3D 轨迹列表框 (Trajectory List Box 3D)。

在 3D 轨迹列表框 (Trajectory List Box 3D) 节点中使用滚动轴 (Scroll Axis) 属性设置用户可以滚动的轴。

要嵌套3D 轨迹列表框 (Trajectory List Box 3D) 节点：

1. 创建3D 轨迹列表框 (Trajectory List Box 3D) 节点。请参阅创建 3D 轨迹列表框 (Trajectory List Box 3D) 节点。
   例如，使用圆形轨迹创建圆形路径。请参阅使用圆形轨迹。
   
2. 选择上一步创建的 3D 轨迹列表框 (Trajectory List Box 3D) 节点，在属性 (Properties) 中将滚动轴 (Scroll Axis) 属性设置为要节点滚动的轴。
   例如，要将 3D 轨迹列表框 (Trajectory List Box 3D) 节点设置成在 x 轴上滚动，将滚动轴 (Scroll Axis) 属性的 X 属性字段设置为 1。
   
3. 创建要在上一步中创建的 3D 轨迹列表框 (Trajectory List Box 3D) 节点中嵌套的 3D 轨迹列表框 (Trajectory List Box 3D) 节点。
   例如，如果要创建相册的多个嵌套 3D 轨迹列表框 (Trajectory List Box 3D) 节点，在预设件 (Prefabs) 中创建 3D 轨迹列表框 (Trajectory List Box 3D) 节点，使用默认圆形轨迹，并将滚动轴 (Scroll Axis) 属性的X 属性字段设置为 1，以将该节点设置为在 x 轴上滚动。
   
4. 在工程 (Project) 中，将项添加到3D 轨迹列表框 (Trajectory List Box 3D) 节点。
   例如，从预设件 (Prefabs) 拖动多个表示相册列表的 3D 轨迹列表框 (Trajectory List Box 3D) 预设件，在每个嵌套 3D 轨迹列表框 (Trajectory List Box 3D) 节点中添加表示各列表中相册的项。
   您可以使用数据源添加项到3D 轨迹列表框 (Trajectory List Box 3D)。请参阅使用数据源。
   

绑定到 3D 轨迹列表框 (Trajectory List Box 3D) 节点以外的属性

要将列表框项的属性绑定到列表框外的节点的属性，应使用别名。

例如，如果您有一个3D 网格列表框 (Grid List Box 3D) 节点或具有3D 文本块 (Text Block 3D) 节点项的3D 轨迹列表框 (Trajectory List Box 3D) 节点，并要将3D 文本块 (Text Block 3D) 节点的文本 (Text) 属性值设置为不在列表框中的3D 空节点 (Empty Node 3D) 节点属性值：

1. 在工程 (Project) 中，按下 Alt 并右键点击包含要绑定到其中的属性的节点并选择别名 (Alias)。请参阅使用别名。
   例如，为3D 空节点 (Empty Node 3D) 节点创建一个别名。
2. 在字典 (Dictionaries) 中确保您创建的别名在列表框节点可以访问的资源字典中。
   例如，将所有别名放到屏幕 (Screen) 节点的资源字典中，或者在列表框节点中创建资源字典，并将别名放在该资源字典中。请参阅使用资源字典。
3. 创建绑定：
   1. 在工程 (Project) 中，选择列表框节点内的节点，您要从其绑定至该列表框节点外的一个节点。
   2. 在属性 (Properties) 中添加绑定 (Bindings) 属性并使用别名创建绑定，以绑定到列表框节点外的节点中的属性。
      例如，在3D 文本块 (Text Block 3D) 节点中，使用您在第一步中创建的别名创建对3D 空节点 (Empty Node 3D) 节点的绑定。请参阅绑定表达式参考。
      例如，使用以下绑定表达式：

      {#Empty Node 3D/TextBlockConcept.Text}

      
      3D 文本块 (Text Block 3D) 节点中的文本 (Text) 属性从3D 空节点 (Empty Node 3D) 节点获取文本 (Text) 属性的值。
   3. 点击保存 (Save)。

从 3D 轨迹列表框 (Trajectory List Box 3D) 节点导航到 页面 (Page) 节点

要从列表框节点中的节点导航到页面 (Page) 节点，应使用别名。例如，如果您使用网格列表框 (Grid List Box) 或3D 轨迹列表框 (Trajectory List Box 3D) 节点创建地址簿，并想要显示页面 (Page) 节点中的地址簿条目的内容。

要从列表框节点导航到页面 (Page) 节点：

1. 在工程 (Project) 中按下 Alt 并右键点击您要导航至其的每个页面 (Page) 节点并选择别名 (Alias)。
   Kanzi Studio 即会创建指向创建它时所在的节点的别名，并将别名放到最近的资源字典中。
   
2. 在字典 (Dictionaries) 中确保您创建的别名在列表框节点可以访问的资源字典中。
   例如，将所有别名放到屏幕 (Screen) 节点的资源字典中，或者在列表框节点中创建资源字典，并将别名放在该资源字典中。请参阅使用资源字典。
   
3. 添加并设置导航至页面 (Navigate to Page) 动作：
   1. 在工程 (Project) 的列表框节点中选择该节点，其中包含您要用于导航到第一步中为其创建别名的一个页面 (Page) 节点的触发器。
      
   2. 在要用于导航到页面 (Page) 节点的触发器的节点组件 (Node Components) > 触发器 (Triggers) 部分添加导航至页面 (Navigate to Page) 动作。
      
   3. 在导航至页面 (Navigate to Page) 设置窗口中，将项 (Item) 属性设置为要导航到的页面 (Page) 节点的别名，并点击保存 (Save)。
      所有别名都以 ＃ 号开头。
      

在预览 (Preview) 中，点击包含导航至页面 (Navigate to Page) 动作的节点，即会激活动作中选定的页面 (Page) 节点。

在用户与 3D 轨迹列表框 (Trajectory List Box 3D) 节点交互时响应

使用 列表框 (List Box) 触发器在用户与 3D 轨迹列表框 (Trajectory List Box 3D) 节点交互时响应。例如，您可以设置用户滚动列表框时 3D 轨迹列表框 (Trajectory List Box 3D) 的外观。

您可通过 3D 轨迹列表框 (Trajectory List Box 3D) 节点使用这些列表框 (List Box) 触发器：

• 列表框: 选定项 (List Box: Item Selected) 触发器在用户选择列表框中的项时触发。
• 列表框: 项隐藏 (List Box: Item Hidden) 触发器在列表框节点中的项从工作内存中卸载时触发。
• 列表框: 项可见性 (List Box: Item Visible) 触发器在列表框节点中的项创建并加载到工作内存中时触发。
• 列表框: 滚动已开始 (List Box: Scroll Started) 触发器在列表框滚动开始时触发。
• 列表框: 已滚动 (List Box: Scrolled) 触发器在列表框节点滚动时触发。
• 列表框: 滚动已完成 (List Box: Scroll Finished) 触发器在列表框滚动结束时触发。
• 列表框: 目标已改变 (List Box: Target Changed) 触发器在用户释放指针停止滚动 3D 轨迹列表框 (Trajectory List Box 3D) 时触发。

要使用带 3D 轨迹列表框 (Trajectory List Box 3D) 节点的列表框 (List Box) 触发器：

1. 创建3D 轨迹列表框 (Trajectory List Box 3D) 节点并向其添加项。请参阅创建 3D 轨迹列表框 (Trajectory List Box 3D) 节点。
   
2. 定义您想通过列表框 (List Box) 触发器设置的行为。
   例如，创建状态机，您可以定义状态以设置 3D 轨迹列表框 (Trajectory List Box 3D) 节点在列表框: 滚动已开始 (List Box: Scroll Started) 和列表框: 滚动已完成 (List Box: Scroll Finished) 触发器被触发时的外观。请参阅创建状态机。
3. 添加和配置列表框 (List Box) 触发器：
   1. 在工程 (Project) 中，选择要为其添加触发器的列表框 (List Box) 节点，并在节点组件 (Node Components) > 触发器 (Triggers) 部分添加其中一个列表框 (List Box) 触发器。
      例如，在工程 (Project) 中选择您在此程序开始时创建的 3D 轨迹列表框 (Trajectory List Box 3D) 节点，并在节点组件 (Node Components) 中添加列表框: 滚动已开始 (List Box: Scroll Started) 触发器。
      
   2. 在您上一步创建的触发器中，选择添加 (Add) 下拉菜单中的动作，并配置该动作。
      例如，选择转到状态 (Go to State) 动作并在动作设置中设置：
      • 项 (Item) 为您在此步骤开始时创建的 3D 轨迹列表框 (Trajectory List Box 3D) 节点
      • 状态 (State) 为设置 3D 轨迹列表框 (Trajectory List Box 3D) 节点在 列表框: 滚动已开始 (List Box: Scroll Started) 触发器被触发时的外观的状态。
      
4. 重复上一步，以添加并配置更多列表框 (List Box) 触发器。
   例如，添加列表框: 滚动已完成 (List Box: Scroll Finished) 触发器。在触发器的转到状态 (Go to State) 动作中，将状态 (State) 设置为设置当触发器被处罚时节点外观的状态。

在预览 (Preview) 中，当滚动您创建的 3D 轨迹列表框 (Trajectory List Box 3D) 节点时，您添加的触发器被触发。

轨迹列表框示例

本示例显示如何使用3D 轨迹列表框 (Trajectory List Box 3D) 节点创建项的交互式可滚动列表。本示例使用动画实现具有选择效果的简单照片库。

3D 轨迹列表框 (Trajectory List Box 3D) 节点、其圆形轨迹 (Circle Trajectory)、3D 轨迹列表框 (Trajectory List Box 3D) 中显示的内容以及突出显示居中照片的动画在 Kanzi Studio 中创建。高亮动画启动的时间点根据滚动速度和轨迹列表框组件产生的用户输入事件中可用的焦点项数据来定义。

本示例中的3D 轨迹列表框 (Trajectory List Box 3D) 节点使用以下功能：

• 滚动轴 (Scroll Axis)。轨迹的滚动轴被设为 x 轴。轨迹定义滚动路径。
• 循环 (Looping)。您可以将3D 轨迹列表框 (Trajectory List Box 3D) 节点中的项限制到定义的轨迹开始和结束位置，或在开始位置和结束位置之间迁移，在本例，使用循环 (Looping) 属性进行限制。
• 轨迹 (Trajectory)。要将轨迹用于3D 轨迹列表框 (Trajectory List Box 3D)，您需在 素材库 (Library) > 轨迹 (Trajectories) 中创建。您可以在Kanzi Studio 中创建圆形和直线轨迹。要使用样条轨迹，在第三方工具中创建样条，将其导入，然后将样条添加为样条轨迹 (Spline Trajectory)。请参阅使用圆形轨迹，使用使用直线轨迹和使用样条轨迹。
  您可以通过添加和设置轨迹属性（如项区域开始 (Item Area Begin)、项区域结束 (Item Area End)、光标偏移 (Cursor Offset)和重写距离 (Override Distance)）来自定义轨迹。
• 选择和目标行为。选择和目标事件分开处理。目标更改消息在用户松开指针时生成。包含与当前轨迹移动中心对齐的项的相关信息。选择消息在用户通过点击或轻敲选择一个项时生成。您可以在 Kanzi Studio 中选择移动到中心 (Bring Center) 选择行为。
  您可以通过设置 列表框: 目标已改变 (List Box: Target Changed) 或 列表框: 选定项 (List Box: Item Selected) 触发器的调用动作，为 3D 轨迹列表框 (Trajectory List Box 3D) 中的任何成员，甚至轨迹列表框组件自身定义目标和选择事件的更多动作。

您可以在 <KanziWorkspace>/Examples/Trajectory_list_box 目录中找到本示例。

在 API 中使用 3D 轨迹列表框 (Trajectory List Box 3D) 节点

要创建 3D 轨迹列表框：

//创建一个名为 MyListBox 的 3D 轨迹列表框。
TrajectoryListBox3DSharedPtr trajectoryListBox = TrajectoryListBox3D::create(domain, "MyListBox");

要设置您希望列表框使用的轨迹：

//创建一个名为 Circle 的半径为 4 个设备无关单位的圆形轨迹。
TrajectorySharedPtr trajectory = Trajectory::createCircle(Vector3(), Vector3::up(), 0.0f, 4.0f, domain, "Circle");

//设置列表框，以使其使用轨迹。
trajectoryListBox->setTrajectory(trajectory);
//增大布局尺寸，以涵盖整个轨迹。
trajectoryListBox->setWidth(10.0f);
trajectoryListBox->setDepth(10.0f);
trajectoryListBox->setHeight(3.0f);

要将项添加到列表框：

//创建立方体网格并将它们添加为轨迹列表框的项。
//轨迹上的项会按您将它们添加到列表中时所用的顺序显示。
Model3DSharedPtr item1 = Model3D::createCube(domain, "item1", 1.0f, ThemeRed);
Model3DSharedPtr item2 = Model3D::createCube(domain, "item2", 1.0f, ThemeGreen);
Model3DSharedPtr item3 = Model3D::createCube(domain, "item3", 1.0f, ThemeBlue);
Model3DSharedPtr item4 = Model3D::createCube(domain, "item4", 1.0f, ThemeOrange);
Model3DSharedPtr item5 = Model3D::createCube(domain, "item5", 1.0f, ThemeYellow);
trajectoryListBox->addItem(item1);
trajectoryListBox->addItem(item2);
trajectoryListBox->addItem(item3);
trajectoryListBox->addItem(item4);
trajectoryListBox->addItem(item5);

要使列表框循环：

//使列表框循环。将所有项都置于轨迹上，以使它们均匀排布。
trajectoryListBox->setLooping(true);

要设置选择行为：

//通过点击项将它们置于轨迹的中心。
trajectoryListBox->setSelectionBehavior(ListBoxConcept::SelectionBehaviorBringToCenter);
//将被点击项位于距离轨迹起点四分之一处时更改位置。
trajectoryListBox->setCursorOffset(0.25f);

有关详细信息，请参阅 API reference中的 TrajectoryListBox3D 类。

3D 轨迹列表框 (Trajectory List Box 3D) 属性类型

要查看 3D 轨迹列表框 (Trajectory List Box 3D) 节点可用属性类型的完整列表，请参阅 Trajectory list box 3D。

另请参阅

使用网格列表框 (Grid List Box) 节点

使用轨迹布局 (Trajectory Layout) 节点

使用 3D 轨迹列表框 (Trajectory List Box 3D) 节点

使用弧形轨迹

使用圆形轨迹

使用椭圆轨迹

使用直线轨迹

使用矩形轨迹

使用螺旋轨迹

使用样条轨迹

使用梯形轨迹

轨迹

使用绑定

使用列表框项容器 (List Box Item Container) 预设件

打开导航